<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="color-scheme" content="light dark" />
    <title>Design Tokens Format Module 2025.10</title>
    <script
      src="https://www.w3.org/Tools/respec/respec-w3c"
      class="remove"
      defer
    ></script>
    <script class="remove">
      const respecConfig = {
        specStatus: 'CG-DRAFT',
        isPreview: true,
        group: 'design-tokens',
        latestVersion: 'https://www.designtokens.org/TR/2025.10/format/',
        prevVersion: null,
        edDraftURI: null, // MUST be null for community group
        editors: [
          { name: 'Louis Chenais', url: 'https://bsky.app/profile/lucho.cool' },
          { name: 'Kathleen McMahon', url: 'https://kathleenmcmahon.dev' },
          { name: 'Drew Powers', url: 'https://pow.rs' },
          { name: 'Matthew Ström-Awn', url: 'https://matthewstrom.com' },
          { name: 'Donna Vitan', url: 'https://www.donnavitan.com' },
        ],
        authors: [
          { name: 'Daniel Banks', url: 'https://x.com/dbanksDesign' },
          { name: 'Mike Kamminga', url: 'https://x.com/mikekamminga' },
          {
            name: 'Ayesha Mazrana (Mazumdar)',
            url: 'https://x.com/AyeshaKMaz',
          },
          { name: 'James Nash', url: 'https://cirrus.twiddles.com' },
          { name: 'Adekunle Oduye', url: 'https://www.adekunleoduye.com' },
          { name: 'Kevin Powell', url: 'https://x.com/kevinmpowell' },
        ],
        github: {
          repoURL: 'https://github.com/design-tokens/community-group',
          branch: 'main',
        },
        tocIntroductory: true,
        logos: [
          {
            src: '/assets/dtcg-logo-on-color.svg',
            url: 'https://www.designtokens.org',
            alt: 'Design Tokens Community Group',
            width: 128,
            height: 128,
            id: 'dtcg-logo',
          },
        ],
      };
    </script>
    <style>
      :root {
        /* Remove watermark negatively impacting readability */
        --unofficial-watermark: none !important;
      }

      .rfc2119 {
        font-style: normal;
        font-size: 0.875em;
      }
    </style>
  </head>

  <body>
    <p class="copyright remove"></p>

    <section id="abstract">
      <p>
        This document describes the technical specification for a file format to
        exchange design tokens between different tools.
      </p>
    </section>

    <section id="sotd">
      <p>
        This section describes the status of this document at the time of its
        publication. Other documents may supersede this document. A list of
        current W3C Community Group reports and the latest revision of this
        report can be found in the W3C Community Group reports index at
        <a href="https://www.w3.org/community/reports/"
          >https://www.w3.org/community/reports/</a
        >.
      </p>
      <p>
        ⚠️ This is a <strong>preview draft</strong> of in progress changes. Do
        not refer to this document directly, and do not implement anything in
        this document.
      </p>
    </section>

    <section id="conformance"></section>

    <section id="introduction">
      <h1>Introduction</h1>

      <p>
        <em>This section is non-normative.</em>
      </p>
      <p>
        Design tokens are a methodology for expressing design decisions in a
        platform-agnostic way so that they can be shared across different
        disciplines, tools, and technologies. They help establish a common
        vocabulary across organizations.
      </p>
      <p>
        There is a growing ecosystem of tools for design system maintainers and
        consumers that incorporate design token functionality, or would benefit
        from doing so:
      </p>
      <ul>
        <li>
          [=Design tools=] have begun allowing designers to label and reference
          shared values for design properties like colors and sizes.
        </li>
        <li>
          [=Translation tools=] exist that can convert source design token data
          into platform-specific source code that can directly be used by
          developers.
        </li>
        <li>
          [=Documentation tools=] can display design token names rather than the
          raw values in design specs and style guides.
        </li>
      </ul>
      <p>
        It is often desirable for design system teams to integrate such tools
        together, so that design token data can flow between design and
        development tools.
      </p>
      <p>For example:</p>
      <ul>
        <li>
          Extracting design tokens from design files and feeding them into
          [=translation tools=] to then be converted into platform-specific code
        </li>
        <li>
          Maintaining a "single source of truth" for design tokens and
          automatically keeping design and development tools in sync with it
        </li>
      </ul>
      <p>
        While many tools now offer APIs to access design tokens or the ability
        to export design tokens as a file, these are all tool-specific. The
        burden is therefore on design system teams to create and maintain their
        own, bespoke "glue" code or workflows. Furthermore, if teams want to
        migrate to different tools, they will need to update those integrations.
      </p>
      <p>
        This specification aims to facilitate better interoperability between
        tools and thus lower the work design system teams need to do to
        integrate them by defining a standard file format for expressing design
        token data.
      </p>
    </section>

    <section
      data-include="./terminology.md"
      data-include-format="markdown"
    ></section>

    <section
      data-include="./file-format.md"
      data-include-format="markdown"
    ></section>

    <section
      data-include="./design-token.md"
      data-include-format="markdown"
    ></section>

    <section
      data-include="./groups.md"
      data-include-format="markdown"
    ></section>

    <section
      data-include="./aliases.md"
      data-include-format="markdown"
    ></section>

    <section data-include="./types.md" data-include-format="markdown"></section>

    <section
      data-include="./composite-types.md"
      data-include-format="markdown"
    ></section>

    <section class="appendix" id="issue-summary"></section>
  </body>
</html>
